---
title: REST API
sidebar:
    order: 4
---
import { Tabs, TabItem } from '@astrojs/starlight/components';

driver-box 提供了一套常用的 REST API，方便开发者结合自身需求将 driver-box 与自身的边缘应用集成起来。

所有接口的响应格式为：

```json title="response"
{
  "success": true,
  "errorCode": 200,
  "errorMsg": "",
  "data": ... //{} 或者 []
}
```
:::tip
下文各接口的响应参数对应的是上述结构中的 `data`  字段。
:::

## 设备服务
### 单点读取
**请求方式：** GET

**请求路径：** /api/v1/device/readPoint

**接口描述：**

设备的单点读取接口会通过 **通讯插件** 发起真实的读操作指令，待指令下发成功后再从设备影子中提取最新点位值。
- 如果插件本身不支持主动的读取操作，则会返回错误。
- 如果被读取的设备不支持同步 IO（例如：发送一个 MQTT 的读指令，其响应时间是不确定），则从影子中获取的数据可能不是最新值。


**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|id|string|是|设备id|
|point|string|是|点位名|

**响应参数**

| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| value | string/int/float | 点位值，字段类型取决于点位类型 |

**示例**

<Tabs>
    <TabItem label="请求">
        ```shell
        curl http://127.0.0.1:8081/api/v1/device/readPoint?id=swtich-1&point=onOff
        ```
    </TabItem>
    <TabItem label="success response" icon="star">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": 1
        }
        ```
    </TabItem>
    <TabItem label="fail response" icon="error">
        ```json
        {
            "success": false,
            "errorCode": 500,
            "errorMsg": "the protocol does not support getting connector",
            "data": null
        }
        ```
    </TabItem>
</Tabs>


### 单点写入
**请求方式：** GET/POST

**请求路径：** /api/v1/device/writePoint

**接口描述：**
设备的单点写入接口会通过 **通讯插件** 发起真实的写操作指令。

**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|id|string|是|设备id|
|point|string|是|点位名|
|value|string/int/float|是|点位值，字段类型取决于点位类型|

**响应参数**

| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| - | -| - |

**示例**

<Tabs>
    <TabItem label="请求">
        ```shell
        curl http://127.0.0.1:8081/api/v1/device/writePoint?id=swtich-1&point=onOff&value=1
        ```
    </TabItem>
    <TabItem label="success response" icon="star">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": null
        }
        ```
    </TabItem>
    <TabItem label="fail response" icon="error">
        ```json
        {
            "success": false,
            "errorCode": 500,
            "errorMsg": "point is readonly, can not write",
            "data": null
        }
        ```
    </TabItem>
</Tabs>

### 批量写入
**请求方式：** POST

**请求路径：** /api/v1/device/writePoint

**接口描述：**
设备的批量写入接口会通过 **通讯插件** 发起真实的写操作指令。

**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|id|string|是|设备id|
|values|array[]|是|点位值数组，数组元素为对象。<br/>对象格式为：`{"name": "点位名", "value": "点位值"}`|

**响应参数**

| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| - | -| - |

**示例**

<Tabs>
    <TabItem label="请求">
        设置空调的开关、模式及温度
        ```shell
        curl -X POST -H "Content-Type: application/json" -d \
            '{"id":"ac_13","values":[{"name":"onOff","value":1},{"name":"runMode","value":1},{"name":"tempSetting","value":28}]}' \
            http://127.0.0.1:8081/api/v1/device/writePoints
        ```
    </TabItem>
    <TabItem label="success response" icon="star">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": null
        }
        ```
    </TabItem>
    <TabItem label="fail response" icon="error">
        ```json
        {
            "success": false,
            "errorCode": 500,
            "errorMsg": "unknown device",
            "data": null
        }
        ```
    </TabItem>
</Tabs>

## 设备影子

### 获取全部设备数据
**请求方式：** GET

**请求路径：** /api/v1/shadow/all

**接口描述：**
获取当前网关中运行着的全部设备影子数据。

**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|-|-|-|-|

**响应参数**
| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| data | Device[] | 设备影子列表 |
<Tabs>
    <TabItem label="Device模型结构">
        | 字段名 | 字段类型 |  字段描述 |
        | ------ | -------- |  -------- |
        |id|string|设备id|
        |points|DevicePoint []|设备点位列表|
        |online|boolean|设备是否在线|
        |ttl|string|设备影子数据过期时间|
        |disconnect_times|int|设备断线次数|
        |updated_at|string|设备影子数据更新时间|
    </TabItem>
    <TabItem label="DevicePoint模型结构">
        | 字段名 | 字段类型 |  字段描述 |
        | ------ | -------- |  -------- |
        |name|string|点位名|
        |value|string|点位值|
        |updated_at|int|最近一次影子更新时间|
        |write_time|int|最近一次点位写入时间|
    </TabItem>
</Tabs>

**示例**

<Tabs>
    <TabItem label="请求">
    ```shell
    curl http://127.0.0.1:8081/api/v1/shadow/all
    ```
    </TabItem>
    <TabItem label="响应">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": [
                {
                    "id": "swtich-1",
                    "points": [
                        {
                            "name": "onOff",
                            "value": 1,
                            "updated_at": "2024-06-05 16:27:41",
                            "write_time": "0001-01-01 00:00:00"
                        }
                    ],
                    "online": true,
                    "ttl": "5m0s",
                    "disconnect_times": 0,
                    "updated_at": "2024-06-05 16:27:41"
                },
                {
                    "id": "swtich-2",
                    "points": [
                        {
                            "name": "onOff",
                            "value": 1,
                            "updated_at": "2024-06-05 16:27:34",
                            "write_time": "0001-01-01 00:00:00"
                        }
                    ],
                    "online": true,
                    "ttl": "5m0s",
                    "disconnect_times": 0,
                    "updated_at": "2024-06-05 16:27:34"
                }
            ]
        }
        ```
    </TabItem>
</Tabs>

### 查询某个设备数据
**请求方式：** GET

**请求路径：** /api/v1/shadow/device

**接口描述：**
获取当前网关中指定设备 ID 的影子数据

**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|id|string|是|设备 ID|

**响应参数**
| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| data | Device | 设备影子 |


**示例**

<Tabs>
    <TabItem label="请求">
        ```shell
        curl http://127.0.0.1:8081/api/v1/shadow/device?id=swtich-1
        ```
    </TabItem>
    <TabItem label="响应">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": {
                "id": "swtich-1",
                "points": [
                    {
                        "name": "onOff",
                        "value": 1,
                        "updated_at": "2024-06-05 16:27:41",
                        "write_time": "0001-01-01 00:00:00"
                    }
                ],
                "online": false,
                "ttl": "5m0s",
                "disconnect_times": 0,
                "updated_at": "2024-06-05 16:32:41"
            }
        }
        ```
    </TabItem>
</Tabs>

### 查询某个设备点位数据
**请求方式：** GET

**请求路径：** /api/v1/shadow/devicePoint

**接口描述：**
获取当前网关中指定设备的某个点位影子数据

**请求参数**

| 字段名 | 字段类型 | 是否必填 | 字段描述 |
| ------ | -------- | -------- | -------- |
|id|string|是|设备 ID|
|point|string|是|点位名|

**响应参数**
| 字段名   | 字段类型   | 字段描述            |
|-------|--------|-----------------|
| data | DevicePoint | 设备影子 |


**示例**

<Tabs>
    <TabItem label="请求">
        ```shell
        curl http://127.0.0.1:8081/api/v1/shadow/devicePoint?id=swtich-1&point=onOff
        ```
    </TabItem>
    <TabItem label="响应">
        ```json
        {
            "success": true,
            "errorCode": 200,
            "errorMsg": "",
            "data": {
                "name": "onOff",
                "value": 1,
                "updated_at": "2024-06-05 16:27:41",
                "write_time": "0001-01-01 00:00:00"
            }
        }
        ```
    </TabItem>
</Tabs>